Repository Labeling Strategies

Introduction

Labels make issue trackers easier to triage, search, automate, and report on. A good label system is small enough to stay consistent and expressive enough to support planning and maintenance.

Purpose

This document provides a reusable label taxonomy for:

• Bugs and incidents
• Features and enhancements
• Operations and maintenance work
• Pull request triage

Architecture Overview

A useful label strategy separates labels by function instead of creating one long undifferentiated list. A practical model uses these groups:

• Type: what kind of work item it is
• Priority: how urgent it is
• Status: where it is in the workflow
• Area: which subsystem it affects
• Effort: rough size or complexity

Suggested Taxonomy

Type labels

• type:bug
• type:feature
• type:docs
• type:maintenance
• type:security
• type:question

Priority labels

• priority:p0
• priority:p1
• priority:p2
• priority:p3

Status labels

• status:needs-triage
• status:blocked
• status:in-progress
• status:ready-for-review

Area labels

• area:networking
• area:containers
• area:security
• area:ci
• area:docs

Effort labels

• size:small
• size:medium
• size:large

Configuration Example

Example policy:

Every new issue gets exactly one type label and one status label.
High-impact incidents also get one priority label.
Area labels are optional but recommended for owned systems.

Example automation targets:

• Auto-add status:needs-triage to new issues
• Route type:security to security reviewers
• Build dashboards using priority:* and area:*

Troubleshooting Tips

Too many labels and nobody uses them

• Reduce the taxonomy to the labels that drive decisions
• Remove near-duplicate labels such as bug and kind:bug
• Standardize prefixes so labels sort clearly

Labels stop reflecting reality

• Review automation rules and board filters
• Make status changes part of the pull request or issue workflow
• Archive labels that no longer map to current processes

Teams interpret labels differently

• Document label meaning in the repository
• Reserve priority labels for response urgency, not personal preference
• Keep type and status labels mutually understandable

Best Practices

• Use prefixes such as type: and priority: for readability and automation
• Keep the total label count manageable
• Apply a small mandatory label set and leave the rest optional
• Review labels quarterly as workflows change
• Match label taxonomy to how the team searches and reports on work

References

• GitHub Docs: Managing labels
• GitHub Docs: Filtering and searching issues and pull requests